'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PCTX_CAPTURE 3CPC "May 13, 2003"
.SH NAME
pctx_capture, pctx_create, pctx_run, pctx_release \- process context library
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \(milpctx [ \fIlibrary\fR... ]
#include <libpctx.h>

\fBtypedef void\fR \fB(pctx_errfn_t)\fR(\fBconst char *\fR\fIfn\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR);
.fi

.LP
.nf
\fBpctx_t *\fR\fBpctx_create\fR(\fBconst char *\fR\fIfilename\fR, \fBchar *const *\fR\fIargv\fR, \fBvoid *\fR\fIarg\fR,
     \fBint\fR \fIverbose\fR, \fBpctx_errfn_t *\fR\fIerrfn\fR);
.fi

.LP
.nf
\fBpctx_t *\fR\fBpctx_capture\fR(\fBpid_t\fR \fIpid\fR, \fBvoid *\fR\fIarg\fR, \fBint\fR \fIverbose\fR,
     \fBpctx_errfn_t *\fR\fIerrfn\fR);
.fi

.LP
.nf
\fBint\fR \fBpctx_run\fR(\fBpctx_t *\fR\fIpctx\fR, \fBuint_t\fR \fIsample\fR, \fBuint_t\fR \fInsamples\fR,
     \fBint (*\fR\fItick\fR)(pctx *, \fBpid_t, id_t, void *));\fR
.fi

.LP
.nf
\fBvoid\fR \fBpctx_release\fR(\fBpctx_t *\fR\fIpctx\fR);
.fi

.SH DESCRIPTION
.sp
.LP
This family of functions allows a controlling process (the process that invokes
them) to create or capture controlled processes.  The functions allow the
occurrence of various events of interest in the controlled process to cause the
controlled process to be stopped, and to cause callback routines to be invoked
in the controlling process.
.SS "\fBpctx_create()\fR and \fBpctx_capture()\fR"
.sp
.LP
There are two ways a process can be acquired by the process context functions.
First, a named application can be invoked with the usual \fIargv\fR[] array
using \fBpctx_create()\fR, which forks the caller and \fBexec\fRs the
application in the child. Alternatively, an existing process can be captured by
its process \fBID\fR using \fBpctx_capture()\fR.
.sp
.LP
Both functions accept a pointer to an opaque handle, \fIarg\fR; this is saved
and treated as a caller-private handle that is passed to the other functions in
the library.  Both functions accept a pointer to a \fBprintf\fR(3C)-like error
routine \fIerrfn\fR; a default version is provided if \fINULL\fR is specified.
.sp
.LP
A freshly-created process is created stopped; similarly, a process that has
been successfully captured is stopped by the act of capturing it, thereby
allowing the caller to specify the handlers that should be called when various
events occur in the controlled process.  The set of handlers is listed on the
\fBpctx_set_events\fR(3CPC) manual page.
.SS "\fBpctx_run()\fR"
.sp
.LP
Once the callback handlers have been set with \fBpctx_set_events()\fR, the
application can be set running using \fBpctx_run()\fR. This function starts the
event handling loop; it returns only when either the process has exited, the
number of time samples has expired, or an error has occurred (for example, if
the controlling process is not privileged, and the controlled process has
\fBexec\fR-ed a setuid program).
.sp
.LP
Every \fIsample\fR milliseconds the process is stopped and the \fItick\fR(\|)
routine is called so that, for example, the performance counters can be sampled
by the caller. No periodic sampling is performed if \fIsample\fR is 0.
.SS "\fBpctx_release()\fR"
.sp
.LP
Once  \fBpctx_run()\fR has returned, the process can be released and the
underlying storage freed using \fBpctx_release()\fR. Releasing the process will
either allow the controlled process to continue (in the case of an existing
captured process and its children) or kill the process (if it and its children
were created using \fBpctx_create()\fR).
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBpctx_capture()\fR and \fBpctx_create()\fR return
a valid handle.  Otherwise, the functions print a diagnostic message and return
\fINULL\fR.
.sp
.LP
Upon successful completion, \fBpctx_run()\fR returns \fB0\fR with the
controlled process either stopped or exited (if the controlled process has
invoked \fBexit\fR(2).) If an error has occurred (for example, if the
controlled process has \fBexec\fR-ed a set-\fBID\fR executable, if certain
callbacks have returned error indications, or if the process was unable to
respond to \fBproc\fR(5) requests) an error message is printed and the function
returns \(mi1.
.SH USAGE
.sp
.LP
Within an event handler in the controlling process, the controlled process can
be made to perform various system calls on its behalf. No system calls are
directly supported in this version of the API, though system calls are executed
by the \fBcpc_pctx\fR family of interfaces in \fBlibcpc\fR such as
\fBcpc_pctx_bind_event\fR(3CPC). A specially created agent \fBLWP\fR is used to
execute these system calls in the controlled process. See \fBproc\fR(5) for
more details.
.sp
.LP
While executing the event handler functions, the library arranges for the
signals \fBSIGTERM\fR, \fBSIGQUIT\fR, \fBSIGABRT\fR, and \fBSIGINT\fR to be
blocked to reduce the likelihood of a keyboard signal killing the controlling
process prematurely, thereby leaving the controlled process permanently stopped
while the agent \fBLWP\fR is still alive inside the controlled process.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
.BR fork (2),
.BR cpc (3CPC),
.BR pctx_set_events (3CPC),
.BR libpctx (3LIB),
.BR proc (5),
.BR attributes (7)
